e-CALLISTO FITS Analyzer
Version 1.7.4
Sahan S Liyanage (sahanslst@gmail.com)
Astronomical and Space Science Unit, University of Colombo, Sri Lanka.

============================================================
README (Linux/Ubuntu)
============================================================

This release is distributed as a zipped folder built with PyInstaller (onedir mode).
After extracting the ZIP, you will see:

  - e-Callisto FITS Analyzer   (executable)
  - _internal/                (required runtime files)

IMPORTANT:
Keep the executable and the _internal folder together in the same directory.
Do not move or rename _internal.

------------------------------------------------------------
1) Quick Start
------------------------------------------------------------

1. Extract the ZIP file.
2. Open a terminal inside the extracted folder.
3. Create and use the launcher script (recommended):

   a) Create a file named: run.sh
   b) Copy the script from section 3 into run.sh
   c) Make it executable:
        chmod +x run.sh
   d) Run the app:
        ./run.sh

You can also run the executable directly, but run.sh is safer because it prevents
Qt environment conflicts and avoids common WebEngine issues.

------------------------------------------------------------
2) Required Packages (Ubuntu / Debian)
------------------------------------------------------------

On Linux, PyInstaller apps may still require a few system libraries.
If you see an error about the Qt "xcb" platform plugin or "libxcb-cursor0",
install the following:

  sudo apt update
  sudo apt install -y libxcb-cursor0

Because this app uses QtWebEngine, these packages are also commonly needed:

  sudo apt install -y \
    libnss3 \
    libxkbcommon0 \
    libxkbcommon-x11-0 \
    libxcb1 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render0 \
    libxcb-render-util0 \
    libxcb-shape0 \
    libxcb-shm0 \
    libxcb-sync1 \
    libxcb-xfixes0 \
    libxcb-xinerama0 \
    libx11-xcb1

After installing, run again using:
  ./run.sh

------------------------------------------------------------
3) Create run.sh (recommended)
------------------------------------------------------------

Create a file named run.sh in the same folder as the executable
(e-Callisto FITS Analyzer). Paste this content exactly:

------------------------------------------------------------
#!/usr/bin/env bash
set -e
cd "$(dirname "$0")"

# Prevent conflicts with user Qt installs (Conda, custom Qt, etc.)
unset QT_PLUGIN_PATH
unset QT_QPA_PLATFORM_PLUGIN_PATH
unset QT_QPA_PLATFORMTHEME

# Safer defaults for systems with limited OpenGL support (QtWebEngine)
export QTWEBENGINE_CHROMIUM_FLAGS="${QTWEBENGINE_CHROMIUM_FLAGS:---disable-gpu --disable-gpu-compositing}"
export QT_OPENGL="${QT_OPENGL:-software}"
export LIBGL_ALWAYS_SOFTWARE="${LIBGL_ALWAYS_SOFTWARE:-1}"
export QTWEBENGINE_DISABLE_SANDBOX="${QTWEBENGINE_DISABLE_SANDBOX:-1}"

exec "./e-Callisto FITS Analyzer" "$@"
------------------------------------------------------------

Then run:

  chmod +x run.sh
  ./run.sh

------------------------------------------------------------
4) Distribution Notes (Important)
------------------------------------------------------------

- Linux builds are not fully dependency-free. Target systems must have required
  system libraries installed (see section 2).
- Tested with Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, and PopOS.

------------------------------------------------------------
5) Troubleshooting
------------------------------------------------------------

A) Error: "Could not load the Qt platform plugin 'xcb'"
--------------------------------------------------------
Install:
  sudo apt install -y libxcb-cursor0

If it still fails, install the full list in section 2 and run using ./run.sh.

B) App opens and closes immediately
-----------------------------------
Run from a terminal to see the real error output:
  ./run.sh

If you ran the executable directly, use run.sh. It clears the conflicting Qt
environment variables that often cause instant exits.

C) WebView / movie panel is blank (QtWebEngine)
------------------------------------------------
Some systems block sandboxing or have GPU driver issues. Run:

  QTWEBENGINE_DISABLE_SANDBOX=1 QT_OPENGL=software LIBGL_ALWAYS_SOFTWARE=1 ./run.sh

------------------------------------------------------------
6) Support Information (When reporting an issue)
------------------------------------------------------------

When you report a packaging or runtime issue, include:

- Ubuntu version:
    lsb_release -a
- The full terminal output from:
    ./run.sh
- Whether you installed the packages listed in section 2

============================================================
End of README
============================================================
